# Modern.js Builder

本章节介绍如何将使用 Modern.js Builder (或 EdenX Builder) 的项目迁移到 Rsbuild。

## 主要区别

Rsbuild 是 Modern.js Builder 的新版本，主要区别如下：

- Rsbuild 的性能更出色，在同时使用 Rspack 的情况下，**Rsbuild 的启动速度和构建速度是 Builder 的 1.5 ~ 2 倍**。
- Rsbuild 仅支持 Rspack 作为打包工具，不再支持 webpack。
- Rsbuild 的 CLI 工具和 dev server 更加强大，支持更多功能。

## 安装依赖

首先你需要把 Builder 相关的 npm 依赖替换为 Rsbuild 的依赖。

import { PackageManagerTabs } from '@theme';

- 移除 Builder 的依赖：

<PackageManagerTabs command="remove @modern-js/builder-cli @modern-js/builder-webpack-provider @modern-js/builder-rspack-provider" />

- 安装 Rsbuild 的依赖：

<PackageManagerTabs command="add @rsbuild/core -D" />

## 更新 npm scripts

下一步，你需要把 package.json 中的 npm scripts 更新为 Rsbuild 的 CLI 命令。

```json title="package.json"
{
  "scripts": {
    "dev": "builder dev", // [!code --]
    "build": "builder build", // [!code --]
    "serve": "builder serve", // [!code --]
    "dev": "rsbuild dev", // [!code ++]
    "build": "rsbuild build", // [!code ++]
    "preview": "rsbuild preview" // [!code ++]
  }
}
```

## 修改配置文件

- 将 `builder.config.ts` 重命名为 `rsbuild.config.ts`。
- 从 `@modern-js/builder-cli` 中导入 `defineConfig` 方法，改为从 `@rsbuild/core` 中导入。
- 将 `builderPlugins` 字段改为 `plugins`。

```ts title="rsbuild.config.ts"
import { defineConfig } from '@modern-js/builder-cli'; // [!code --]
import { defineConfig } from '@rsbuild/core'; // [!code ++]

export default defineConfig({
  builderPlugins: [], // [!code --]
  plugins: [], // [!code ++]
});
```

## 替换插件

Rsbuild 和 Builder 的插件系统不兼容，因此需要将 Builder 的插件替换为 Rsbuild 的插件。

下面是 Builder 插件和 Rsbuild 插件的对应关系：

| Builder                                  | Rsbuild                                                                                           |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
| @modern-js/builder-plugin-vue            | [@rsbuild/plugin-vue](/plugins/list/plugin-vue)                                                   |
| @modern-js/builder-plugin-vue2           | [@rsbuild/plugin-vue2](https://github.com/rspack-contrib/rsbuild-plugin-vue2)                     |
| @modern-js/builder-plugin-stylus         | [@rsbuild/plugin-stylus](/plugins/list/plugin-stylus)                                             |
| @modern-js/builder-plugin-node-polyfill  | [@rsbuild/plugin-node-polyfill](https://github.com/rspack-contrib/rsbuild-plugin-node-polyfill)   |
| @modern-js/builder-plugin-image-compress | [@rsbuild/plugin-image-compress](https://github.com/rspack-contrib/rsbuild-plugin-image-compress) |
| @modern-js/builder-plugin-swc            | 默认生效，无须使用                                                                                |
| @modern-js/builder-plugin-esbuild        | 不再支持                                                                                          |

以 `@modern-js/builder-plugin-vue` 为例，你需要先安装 `@rsbuild/plugin-vue`，然后在 `rsbuild.config.ts` 中引入插件，并添加到 `plugins` 字段中。

```ts title="rsbuild.config.ts"
import { builderPluginVue } from '@modern-js/builder-plugin-vue'; // [!code --]
import { pluginVue } from '@rsbuild/plugin-vue'; // [!code ++]

export default defineConfig({
  builderPlugins: [builderPluginVue()], // [!code --]
  plugins: [pluginVue()], // [!code ++]
});
```

## 添加 React 相关插件

Rsbuild 不与任何前端 UI 框架耦合。因此，如果你是一个 React 项目，需要手动添加 [React 插件](/plugins/list/plugin-react)：

```ts title="rsbuild.config.ts"
import { pluginReact } from '@rsbuild/plugin-react';

export default {
  plugins: [pluginReact()],
};
```

如果你当前项目中有使用 SVGR，还需要注册 Rsbuild 的 [SVGR 插件](/plugins/list/plugin-svgr)：

```ts title="rsbuild.config.ts"
import { pluginSvgr } from '@rsbuild/plugin-svgr';

export default {
  plugins: [pluginSvgr()],
};
```

如果你是其他框架的使用者，可参考 [插件列表](/plugins/list/index) 选择对应的框架插件。

## 配置迁移

Rsbuild 和 Builder 的绝大多数配置项是一致的，仅有少许配置项进行了调整。

你可以通过 [Rsbuild 配置项](/config/index) 来查看 Rsbuild 的配置项。

值得注意的是，相比 Builder，**Rsbuild 中一些默认值和行为存在差异**：

- 浏览器范围：默认最低兼容到支持 [原生 ES Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) 的浏览器，可参考 [Browserslist 默认值](/guide/advanced/browserslist#browserslist-默认值)。
- HTML 文件输出位置：默认输出到 dist 目录的根部，可参考 [默认产物目录](/guide/basic/output-files#默认产物目录)。
- Polyfill 注入方式：默认按需注入，可参考 [output.polyfill](/config/output/polyfill)。
- TypeScript 类型检查：默认不开启，需要手动注册 [@rsbuild/plugin-type-check](https://github.com/rspack-contrib/rsbuild-plugin-type-check)。
- 修改 DevServer 配置：通过 `dev` 和 `server` 配置项修改。

## 验证结果

完成以上步骤后，你已经完成了从 Modern.js Builder 到 Rsbuild 的基本迁移，此时可以执行 `npm run dev` 命令来尝试启动开发服务器。

如果在构建过程中发现问题，请根据错误日志进行调试。

## 内容补充

当前文档只涵盖了迁移过程的部分事项，如果你发现有合适的内容可以补充，欢迎通过 pull request 来完善文档 🤝。

> Rsbuild 的文档位于 [rsbuild/website](https://github.com/web-infra-dev/rsbuild/tree/main/website) 目录。
